home *** CD-ROM | disk | FTP | other *** search
/ Aminet 24 / Aminet 24 (1998)(GTI - Schatztruhe)[!][Apr 1998].iso / Aminet / dev / c / vbcc.lha / readme.vbcc next >
Text File  |  1998-02-19  |  19KB  |  640 lines
  1.  
  2.  
  3. vbcc - portable ANSI C compiler (c) in 1995-98 by Volker Barthelmann
  4.  
  5.  
  6. INTRODUCTION
  7.  
  8.     vbcc is a free portable and retargetable ANSI C compiler.
  9.  
  10.     This archive contains the compiler, preprocessor, assembler, linker,
  11.     frontend, message browser, startup codes, C-libraries, amiga.lib
  12.     replacements as well as several other tools (mostly with complete
  13.     source) for 68k as well as PPC.
  14.  
  15.     This gives you a complete system that allows to develop programs in
  16.     ANSI C as well as Amiga-specific programs (provided you obtain the
  17.     OS-includes) running on 68k or PowerUp-boards.
  18.  
  19.     All major parts of this distribution (including compiler, preprocessor,
  20.     libraries etc.) have been compiled/assembled with this system and
  21.     apart from the OS-includes everything is included to rebuilt vbcc,
  22.     the libraries and many of the other programs.
  23.  
  24.     Note that the programs in this archive all run on the 68k even when
  25.     generating PPC-code. There is another archive which contains compilers
  26.     that run on the PPC.
  27.  
  28.  
  29. FEATURES
  30.  
  31.     vbcc..
  32.  
  33.     - comes with source
  34.  
  35.     - is free
  36.  
  37.     - is portable and retargetable
  38.  
  39.     - comes with a global optimizer that can e.g. do global common
  40.       subexpression elimination, constant propagation, function inlining
  41.       and several other optimizations (but is not yet finished and may
  42.       have some bugs)
  43.  
  44.     - should be ANSI compliant
  45.  
  46.     - can generate code that runs on a plain 68000 CPU
  47.  
  48.     - can generate code optimized for 020/030, 040 or 060
  49.  
  50.     - can generate code that uses the 68881/2, 68040/060 FPUs directly
  51.       and comes with appropriate math-libraries
  52.  
  53.     - can generate code that runs on PowerUp-boards
  54.  
  55.     - generates standard Amiga-68k-objects or PPC-ELF-objects
  56.  
  57.     - does not need too much memory
  58.  
  59.     - comes with a message browser
  60.  
  61.     - comes with a config program
  62.  
  63.     - offers a lot of error/warning messages that can be turned on/off
  64.       separately
  65.  
  66.  
  67. REQUIREMENTS
  68.  
  69.     To use vbcc you need:
  70.  
  71.     - an Amiga with OS 2.0 or higher
  72.  
  73.     - enough RAM (it is possible to translate small programs with 1MB, but
  74.       for larger programs much more will be needed)
  75.  
  76.     Stuff that is not needed, but may be very useful:
  77.  
  78.     - harddisk
  79.  
  80.     - editor
  81.  
  82.     - make, touch etc.
  83.  
  84.     - the Amiga OS-includes (they can be found on certain CDs)
  85.  
  86.     - pipe-command (to use the message browser)
  87.  
  88.     Also you should know how to use the shell and you should know ANSI C
  89.     (if you need a book I recommend (like everyone) "The C Programming
  90.     Language, Second Edition, ANSI C" by Kernighan and Ritchie).
  91.  
  92.  
  93. LEGAL
  94.  
  95.     Note that this distribution contains several programs, libraries etc.
  96.     that are from different authors and are under different legal status.
  97.     So always read the corresponding doc/guide-file to find out under
  98.     what conditions a certain file may be used, distributed etc.
  99.  
  100.     For the most part you can assume that you may use everything for
  101.     non-commercial purposes and may distribute the unchanged archive
  102.     in whole.
  103.  
  104.     Changing any parts from this archive, distributing parts of it or
  105.     using it commercially might be legal for certain parts, but illegal
  106.     for others, so read all docs carefully before doing any of the above.
  107.  
  108.     This archive contains code written by (this list may be incomplete):
  109.  
  110.     Volker Barthelmann, Frank Wille, Thorsten Schaaps, Dennis Ritchie,
  111.     Matthias Fleischer, Gunther Nikl, Mike Schwartz, Kasper Graversen,
  112.     Johnny Tevessen
  113.  
  114.     However, if you have any comments/problems etc. with anything, please
  115.     do not bother them, but write to me (volker@vb.franken.de) first.
  116.     Exceptions are the parts by Kasper Graversen.
  117.  
  118.  
  119. INSTALLATION/TUTORIAL
  120.  
  121.     [Names of directories, binaries or assigns have changed since earlier
  122.      versions as have config-files. So users of earlier versions should
  123.      read this again and do a complete re-install to avoid problems.]
  124.  
  125.     The first step (which you probably already did) is to extract the
  126.     entire archive (take care to preserve the file attributes).
  127.  
  128.     The distributed programs are for the most part only usable from a shell.
  129.  
  130.     To use vbcc the following steps are necessary:
  131.  
  132.     1. Assign vbccm68k: to the subdirectory vbcc/machines/amiga68k,
  133.               vbccppc:  to the subdirectory vbcc/machines/amigappc and
  134.               vbcc: to vbccm68k:
  135.  
  136.     2. Assign vlibm68k: to vbccm68k:lib and
  137.               vlibppc:  to vbccppc:lib.
  138.  
  139.     3. Assign vincludem68k: to vbccm68k:include and
  140.               vincludeppc:  to vbccppc:include.
  141.  
  142.        If you have the OS-includes you can either add the path to this
  143.        assign, e.g.
  144.  
  145.         assign vincludem68k: vbccm68k:include myhd:os-includes
  146.         assign vincludeppc:  vbccppc:include  myhd:os-includes
  147.  
  148.        or you can modify the vc.config (see below).
  149.  
  150.        If you want to use ixemul.lib assign ixinclude: to the directory
  151.        containing the ixemul-includes.
  152.  
  153.     4. Add vbccm68k://bin, vbccm68k:bin and vbccppc:bin to your path.
  154.  
  155.     5. set the stack to a reasonable value (perhaps some 10k).
  156.  
  157.     If you use vbcc frequently it is probably a good idea to add those
  158.     commands to your user-startup, shell-startup or similar.
  159.     However if you just want to try it out the sample script init_vbcc in
  160.     the subdirectory machines/amiga68k does all this for you.
  161.     You have to cd in its directory and start it from there, e.g.:
  162.  
  163.         cd myhd:vbcc/machines/amiga68k
  164.         init_vbcc
  165.  
  166.     Now you should be able to use vbcc. E.g. if you want to compile and
  167.     link the program hello.c you can type
  168.  
  169.         vc hello.c
  170.  
  171.     This will compile and link the file hello.c and create the executable
  172.     a.out in the current directory.
  173.  
  174.         vc hello.c -o hello
  175.  
  176.     will do the same, but the created executable will be called hello.
  177.  
  178.         vc -c t1.c t2.c
  179.  
  180.     will compile t1.c and t2.c without linking, creating the object files
  181.     t1.o and t2.o.
  182.  
  183.         vc t1.o t2.o -o tt
  184.  
  185.     will link them together and create the executable tt.
  186.  
  187.     If your program uses floating point add -lmieee to the commandline
  188.     to link with the math-library, e.g.:
  189.  
  190.         vc calc.c -o calc -lmieee
  191.  
  192.     There is also an extra.lib which includes a few functions that are
  193.     no standard ANSI functions but some people seem to regard them as
  194.     standard functions. If you use one of these add -lextra to the
  195.     commandline and read:
  196.  
  197.         vbcc/machines/amiga68k/doc/extralib.doc
  198.  
  199.     For further information read the files:
  200.  
  201.         vbcc/doc/vbcc.doc
  202.         vbcc/doc/vc.doc
  203.         vbcc/doc/vbccm68k.doc
  204.         vbcc/machines/amiga68k/doc/vclib.doc
  205.  
  206.  
  207. PPC-SUPPORT
  208.  
  209.     If you want to generate PPC-code, all you have to do is to add +ppc
  210.     to your command-line.
  211.  
  212.         vc +ppc hello.c -o hello
  213.  
  214.     will create the ELF-executable called hello. To execute it, type
  215.  
  216.         ppcrun hello
  217.  
  218.     If a PPC-program expects arguments attach them:
  219.  
  220.         ppcrun hello 1 2 "test 3"
  221.  
  222.     Options specific to the 68k can of course not be used for PPC. See
  223.     doc/vbccppc.doc and machines/amigappc/doc/* for further information.
  224.  
  225.     CAUTION: Note that if you write programs using AmigaOS-functions you
  226.              have to specify -amiga-align! You might want to add it to
  227.              vbcc:ppc if you usually use AmigaOS-functions.
  228.  
  229.     Note that PPC-support should be considered beta and there is room
  230.     for many improvements.
  231.  
  232.  
  233. CONFIGURATION
  234.  
  235.     The frontend searches for a file vc.config in ENV: and vbcc: to read
  236.     preferences. The provided sample vc.config should be usable and does
  237.     not have to be changed but you can add something to suit your personal
  238.     preferences - read
  239.  
  240.         vbcc/doc/vc.doc
  241.  
  242.     to find out more.
  243.  
  244.     If you have the OS-includes and do not want to add them to the vinclude:
  245.     assign mentioned above you can also modify the vc.config file:
  246.  
  247.     Add -I<full_path> directly after the two occurences of -Ivinclude*: in
  248.     the sample vc.config, e.g.:
  249.  
  250.         -pp=vcpp -Ivincludem68k: -Imyhd:os-include -D__STDC__=1 %s %s %s
  251.         -ppv=vcpp -Ivincludem68k: -Imyhd/os-include -D__STDC__=1 %s %s %s
  252.  
  253.  
  254. MESSAGE BROWSER
  255.  
  256.     If you start the message browser with
  257.  
  258.         run vbrowse
  259.  
  260.     it wi